home *** CD-ROM | disk | FTP | other *** search
/ MacTech 1 to 12 / MacTech-vol-1-12.toast / Source / MacTech® Magazine / Volume 06 - 1990 / 06.12 Dec 90 / dissMask Source / dissMask.h < prev    next >
Encoding:
C/C++ Source or Header  |  1990-07-09  |  3.5 KB  |  76 lines  |  [TEXT/KAHL]
  1. /*
  2.     dissMask.h -- Copyright © 1990 by Michael S. Morton.  All rights reserved.
  3.  
  4.     dissMask is a set of functions which allow you to perform a digital “dissolve”
  5.     using a series of calls to QuickDraw’s CopyMask() function.  These functions
  6.     don’t do anything graphical directly; they just enable you to do so by rapidly
  7.     generating a sequence of masks.
  8.  
  9.     Advantages of this scheme include:
  10.     •    It’s completely hardware-independent.  Because QuickDraw does the actual
  11.         graphics work, the only low-level work is done on an old-fashioned bitmap,
  12.         the format of which is stable.
  13.     •    This means (same advantage, continued) that it works at any bit depth and
  14.         with multiple-monitor targets.
  15.     •    Because the client gets to choose how many black pixels are added to the
  16.         mask in between copies, they can to some degree control the speed of the
  17.         dissolve.  The client can empirically measure the time for the first copy,
  18.         and do “mid-course correction” to get the desired speed.
  19.     •    On Mac II ROMs and later, stretching works.
  20.  
  21.     Disadvantages include:
  22.     •    Low memory may prevent allocating the bitmap.
  23.     •    The maximum speed can be obtained only by reducing the number of CopyMask
  24.         calls, making the appearance “chunky”.
  25.     •    Large areas dissolve slowly and with a lot of flashing.
  26. */
  27.  
  28. #include "MacTypes.h"                                        /* for Rect type */
  29. #include "QuickDraw.h"                                    /* for BitMap type */
  30.  
  31. typedef struct
  32. {    /*    PUBLIC section: these variables are read-only for the client */
  33.     BitMap maskMap;                                                /* mask bitmap for client to pass to CopyMask */
  34.     Rect maskRect;                                                /* mask rectangle for client to pass to CopyMask */
  35.     unsigned long pixLeft;                                /* number of bits remaining to copy */
  36.  
  37.     /*    PRIVATE section: */
  38.     unsigned long seqElement;                            /* current element of sequence */
  39.     unsigned long seqMask;                                /* mask used to generate sequence */
  40. } dissMaskInfo;                                                    /* define this type */
  41.  
  42. /*    dissMaskInit -- Initialize a “dissMaskInfo” structure, based solely on the
  43.         bounds of the source rectangle.  This is the same rectangle passed to CopyMask()
  44.         as the “srcRect” parameter.
  45.  
  46.         There will be a slight increase in performance if the srcRect’s dimensions are
  47.         each near or equal to (but not over) a power of two.  This increase will be more
  48.         noticeable if there are fewer CopyMask() calls.
  49.  
  50.         Under certain conditions, the function may fail, in which case it returns FALSE.
  51.         These include running out of memory and the case where the source rectangle is
  52.         ridiculously small.  The client should just do a vanilla CopyBits() call if a
  53.         failure is reported.
  54.  
  55.         In addition to filling in the dissMaskInfo structure with the BitMap and Rect
  56.         for use with CopyMask(), the “pixLeft” field is set up.  This is the count of
  57.         pixels left to turn black in the mask.  It MAY be more than the number of
  58.         pixels in the specified rectangle.  The client should advance the mask until
  59.         this field is zero.
  60. */
  61. extern Boolean dissMaskInit (Rect *srcRect, dissMaskInfo *info);
  62.  
  63. /*    dissMaskNext -- “Advance” the mask bitmap by the specified number of pixels.
  64.         Advancing in small steps will cause a slower, smoother dissolve.  Advancing
  65.         in large steps will cause a faster, less smooth effect.
  66.  
  67.         You should hide, or at least obscure, the cursor before entering the loop
  68.         with the CopyMask() calls.
  69. */
  70. extern void dissMaskNext (dissMaskInfo *info, unsigned long steps);
  71.  
  72. /*    dissMaskFinish -- Clean up the internals of the information struct.  Always
  73.         call this when the client is done.
  74. */
  75. extern void dissMaskFinish (dissMaskInfo *info);
  76.